feat: middleware entrypoint #241

deanmlittle · 2025-09-05T10:53:44Z

This PR implements the middleware_entrypoint! macro. This macro enables users to define a hot path that skips entrypoint deserialization for high priority instructions, with a fallback to a cold path in the case that it does not return SUCCESS.

Attached is a simple code sample of how it can be used in practice, where an invocation with zero accounts will lead to the hot path, and anything else will fallback to the cold path:

#![cfg_attr(target_os = "solana", no_std)]
use pinocchio::{ProgramResult, account_info::AccountInfo, middleware_entrypoint, msg, no_allocator, nostd_panic_handler, pubkey::Pubkey};

nostd_panic_handler!();
no_allocator!();

middleware_entrypoint!(hot,cold);

// This uses 4 CUs
#[inline(always)]
pub fn hot(input: *mut u8) -> u64 {
    unsafe { *input as u64 }
}

// This uses 113 CUs
#[cold]
#[inline(always)]
pub fn cold(
    _program_id: &Pubkey,
    _accounts: &[AccountInfo],
    _instruction_data: &[u8],
) -> ProgramResult {
    msg!("Hello from my Pinocchio!");
    Ok(())
}

sdk/pinocchio/src/entrypoint/middleware.rs

Co-authored-by: Fernando Otero <[email protected]>

sdk/pinocchio/src/entrypoint/middleware.rs

Co-authored-by: Fernando Otero <[email protected]>

LStan · 2025-09-09T18:03:38Z

README.md


+📌 [`middleware_program_entrypoint!`](https://docs.rs/pinocchio/latest/pinocchio/macro.middleware_program_entrypoint.html)
+
+The `middleware_program_entrypoint!` macro defines a dual entrypoint implementation consisting of a `hot` path which bypasses entrypoint deserialization, and a `cold` path with behaves like a regular pinocchio entrypoint that has undergone `program_entrypoint!` deserialization. This gives the user flexibility to implement extreme CU optimizations against the most critical paths in their proggram with the convenience of being able to fallback to a regular pinocchio program to manage the fail case and other instructions that do not require such optimizations.


Suggested change

The `middleware_program_entrypoint!` macro defines a dual entrypoint implementation consisting of a `hot` path which bypasses entrypoint deserialization, and a `cold` path with behaves like a regular pinocchio entrypoint that has undergone `program_entrypoint!` deserialization. This gives the user flexibility to implement extreme CU optimizations against the most critical paths in their proggram with the convenience of being able to fallback to a regular pinocchio program to manage the fail case and other instructions that do not require such optimizations.

The `middleware_program_entrypoint!` macro defines a dual entrypoint implementation consisting of a `hot` path which bypasses entrypoint deserialization, and a `cold` path which behaves like a regular pinocchio entrypoint that has undergone `program_entrypoint!` deserialization. This gives the user flexibility to implement extreme CU optimizations against the most critical paths in their program with the convenience of being able to fallback to a regular pinocchio program to manage the fail case and other instructions that do not require such optimizations.

LStan · 2025-09-09T18:04:01Z

README.md

+nostd_panic_handler!();
+no_allocator!();
+
+middleware_program_entrypoint!(hot,cold);


Suggested change

middleware_program_entrypoint!(hot,cold);

middleware_program_entrypoint!(hot, cold);

LStan · 2025-09-09T18:04:26Z

sdk/pinocchio/src/entrypoint/middleware.rs

+/// nostd_panic_handler!();
+/// no_allocator!();
+/// 
+/// middleware_program_entrypoint!(hot,cold);


Suggested change

/// middleware_program_entrypoint!(hot,cold);

/// middleware_program_entrypoint!(hot, cold);

LStan · 2025-09-09T18:09:42Z

sdk/pinocchio/src/entrypoint/middleware.rs

+            }
+        }
+    };
+}


Suggested change

}

}

deanmlittle · 2025-09-11T06:59:07Z

@febo I have added a feature flag called asm that allows advanced users to consume assembly macros that help them save every last CU on their hot path by only ever manually overriding the return register to an error code in assembly is needed in the hot path. If the hot path does not explicitly exit, the cold path will then be executed directly inline afterwards without the need for a jmp or call instruction, and the resulting numeric type will be converted to a u32 and manually override the value of the return register in assembly accordingly.

febo · 2025-09-11T11:29:16Z

sdk/pinocchio/src/entrypoint/middleware.rs

+        unsafe {
+            core::arch::asm!(
+                "mov32 r0, {0}",
+                in(reg) $value
+            );
+        }


Should we add a compile-time check that $value is a u32?

Suggested change

unsafe {

core::arch::asm!(

"mov32 r0, {0}",

in(reg) $value

);

}

unsafe {

let v: u32 = $value;

core::arch::asm!(

"mov32 r0, {0}",

in(reg) v

);

}

feat: middleware entrypoint

e5f42d0

febo reviewed Sep 5, 2025

View reviewed changes

sdk/pinocchio/src/entrypoint/middleware.rs Outdated Show resolved Hide resolved

febo reviewed Sep 5, 2025

View reviewed changes

sdk/pinocchio/src/entrypoint/middleware.rs Outdated Show resolved Hide resolved

deanmlittle and others added 2 commits September 5, 2025 19:21

Update sdk/pinocchio/src/entrypoint/middleware.rs

fa62057

Co-authored-by: Fernando Otero <[email protected]>

Update sdk/pinocchio/src/entrypoint/middleware.rs

60379aa

Co-authored-by: Fernando Otero <[email protected]>

febo reviewed Sep 5, 2025

View reviewed changes

sdk/pinocchio/src/entrypoint/middleware.rs Show resolved Hide resolved

deanmlittle and others added 2 commits September 5, 2025 20:25

Update sdk/pinocchio/src/entrypoint/middleware.rs

57a94b0

Co-authored-by: Fernando Otero <[email protected]>

documentation and typo fixes

d3d3c95

LStan reviewed Sep 9, 2025

View reviewed changes

Added feature for assembly-level entrypoint optimizations

d07ad3b

febo reviewed Sep 11, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: middleware entrypoint #241

feat: middleware entrypoint #241

Uh oh!

deanmlittle commented Sep 5, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

LStan Sep 9, 2025

Uh oh!

LStan Sep 9, 2025

Uh oh!

LStan Sep 9, 2025

Uh oh!

LStan Sep 9, 2025

Uh oh!

deanmlittle commented Sep 11, 2025

Uh oh!

febo Sep 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		📌 [`middleware_program_entrypoint!`](https://docs.rs/pinocchio/latest/pinocchio/macro.middleware_program_entrypoint.html)

		The `middleware_program_entrypoint!` macro defines a dual entrypoint implementation consisting of a `hot` path which bypasses entrypoint deserialization, and a `cold` path with behaves like a regular pinocchio entrypoint that has undergone `program_entrypoint!` deserialization. This gives the user flexibility to implement extreme CU optimizations against the most critical paths in their proggram with the convenience of being able to fallback to a regular pinocchio program to manage the fail case and other instructions that do not require such optimizations.

	middleware_program_entrypoint!(hot,cold);
	middleware_program_entrypoint!(hot, cold);

	/// middleware_program_entrypoint!(hot,cold);
	/// middleware_program_entrypoint!(hot, cold);

+                          }
+                      }
+                  };
+              }

                
                    No newline at end of file

feat: middleware entrypoint #241

Are you sure you want to change the base?

feat: middleware entrypoint #241

Uh oh!

Conversation

deanmlittle commented Sep 5, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

LStan Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

LStan Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

LStan Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

LStan Sep 9, 2025

Choose a reason for hiding this comment

Uh oh!

deanmlittle commented Sep 11, 2025

Uh oh!

febo Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants